/*
 * $Id: QEContact.h 248 2008-09-08 15:31:38Z jon $
 * Sleeper
 *
 * Created by Jon Gordon on 7/28/08
 * Copyright Jon Gordon.  All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining 
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including 
 * without limitation the rights to use, copy, modify, merge, publish, 
 * distribute, sublicense, and/or sell copies of the Software, and to 
 * permit persons to whom the Software is furnished to do so, subject to 
 * the following conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */


#import <Cocoa/Cocoa.h>


//
// Represents a single contact in the contest log.
//
// Author: $Author: jon@bway.net $
// Version $Revision: 2 $
//
@interface QEContact : NSObject <NSCoding, NSCopying> {
@private
    NSString *call;
    NSNumber *check;
    NSNumber *serialSent;
    NSNumber *freq;
    NSString *prec;
    NSString *section;
    NSNumber *serialRcvd;
    NSDate   *time;
    
    id       extension;
}

/*
 * Main initializer for this class, setting all fields of the contact.
 */
- (id)initWithSerialSent:(NSNumber *)newSerialSent
                    time:(NSDate *)newTime
                    freq:(NSNumber *)newFreq
                    call:(NSString *)newCall
              serialRcvd:(NSNumber *)newSerialRcvd
                    prec:(NSString *)newPrec
                   check:(NSNumber *)newCheck
                 section:(NSString *)newSection;

//
// Gets the contact number.  Each contact in the log should have a contact number,
// which is 1 for the first contact, and goes up by 1 for each subsequent contact.
// In other words, it is a serial number, but the term is not used here to avoid
// any possible confusion with the "serial" element, which represents the serial
// number sent by the other station.
//
// return:
//  contact number
//
- (NSNumber *)serialSent;

//
// Sets the contact number.  Each contact in the log should have a contact number,
// which is 1 for the first contact, and goes up by 1 for each subsequent contact.
// In other words, it is a serial number, but the term is not used here to avoid
// any possible confusion with the "serial" element, which represents the serial
// number sent by the other station.
//
// parameter:
//  newSerialSent - new contact number
//
- (void)setSerialSent:(NSNumber *)newSerialSent;

//
// Validates the contact index according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validateSerialSent:(id *)ioValue error:(NSError **)outError;

//
// Gets the frequency.
//
// return:
//  the frequency (in kHz)
//
- (NSNumber *)freq;

//
// Sets the frequency.
//
// parameter:
//  newFrequency - the frequency to set (in kHz)
//
- (void)setFreq:(NSNumber *)newFrequency;

//
// Validates the frequency according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validateFreq:(id *)ioValue error:(NSError **)outError;

//
// Gets the call sign of the other station.
//
// return:
//  the callsign
//
- (NSString *)call;

//
// Sets the call sign of the other station.
//
// parameter:
//  newCallsign - the call sign of the other station
//
- (void)setCall:(NSString *)newCallsign;

//
// Validates the callsign according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validateCall:(id *)ioValue error:(NSError **)outError;

//
// Gets the serial sent by the other station.
//
// return:
//  the serial
//
- (NSNumber *)serialRcvd;

//
// Sets the serial sent by the other station.
//
// parameter:
//  newSerialRcvd - the serial sent by the other station
//
- (void)setSerialRcvd:(NSNumber *)newSerialRcvd;

//
// Validates the serial according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validateSerialRcvd:(id *)ioValue error:(NSError **)outError;

//
// Gets the precedence sent by the other station.
//
// return:
//  the precedence
//
- (NSString *)prec;

//
// Sets the precedence sent by the other station.
//
// parameter:
//  newPrecedence - the precedence sent by the other station
//
- (void)setPrec:(NSString *)newPrecedence;

//
// Validates the precedence according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validatePrec:(id *)ioValue error:(NSError **)outError;

//
// Gets the check sent by the other station.
//
// return:
//  the check
//
- (NSNumber *)check;

//
// Sets the check sent by the other station.
//
// parameter:
//  newCheck - the check sent by the other station
//
- (void)setCheck:(NSNumber *)newCheck;

//
// Validates the check according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validateCheck:(id *)ioValue error:(NSError **)outError;

//
// Gets the ARRL/RAC section sent by the other station.
//
// return:
//  the section
//
- (NSString *)section;

//
// Sets the ARRL/RAC section sent by the other station.
//
// parameter:
//  newSection - the ARRL/RAC section sent by the other station
//
- (void)setSection:(NSString *)newSection;

//
// Validates the section according to KVC.  See the _Key-Value_Coding_Program-
// ming_Guide_ for more information.
//
// parameters:
//  ioValue  - pointer to reference to potential new value, which is to 
//             be validated
//  outError - pointer to reference to Error object, in case ioValue points
//             to an invalid, unvalidatable value
//
- (BOOL)validateSection:(id *)ioValue error:(NSError **)outError;

//
// Gets the date and time of the contact.
//
// return:
//  the date and time
//
- (NSDate *)time;

//
// Sets the date and time of the contact.
//
// parameter:
//  newTime - the date and time
//
- (void)setTime:(NSDate *)newTime;

@end
